HAL MMC migration: List of applicable concepts

This section provides information about the applicable HAL MMC architecture concepts.

Concepts for MMC driver

Concept	Description here
Separation of initialization and configuration functions	The initialization has been split into separate init and config functions: HAL_MMC_Init: initializes the handle and links it to an MMC instance. HAL_MMC_SetConfig: configure the MMC according to the user parameters.
Removal and conversion of init structure to configuration structure	The init structure has been removed from the handle and converted into hal_mmc_config_t configuration structure.
Renaming of the handle structure	The handle structure has been renamed to hal_mmc_handle_t.
Renaming unitary init structures	The MMC_InitTypeDef structure is no longer available and has been replaced by hal_mmc_config_t.
Remove MspInit and MspDeInit callbacks	hal_mmc_MspInit and hal_mmc_MspDeInit are no longer available, they are replaced by a user sequence to initialize and configure the MMC.
Unitary configuration APIs	New APIs are introduced to individually Set and Get specific MMC configuration parameters, allowing for more granular control and flexibility: HAL_MMC_SetDataTimeout(), HAL_MMC_GetDataTimeout().
Introduction of HAL user data set/get APIs	Two functions to set and get user data are available: HAL_MMC_SetUserData(), HAL_MMC_GetUserData().
Individual callback registration APIs replace global register and unregister functions	The callback registration is handled by specific functions for each MMC event. These functions are used to register callback functions for different MMC events.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL MMC driver, and equivalent services are ensured through the LL APIs.
Revised and optimized HAL state machine	The MMC is now managed by a global state machine, which centralizes the control and monitoring of MMC operations: hal_mmc_state_t.
Revised and optimized HAL API status returns	The HAL MMC functions were updated to return: HAL_INVALID_PARAM: in case of a NULL p_config structure pointer. HAL_ERROR: in case of an error. HAL_TIMEOUT: in case of a user timeout. HAL_BUSY: in case of an ongoing process. HAL_OK: in case of a successfully completed operation.
Revised and optimized HAL error management	The HAL error handling mechanisms have been redesigned to improve the detection, reporting, and handling of errors. This rework aims to provide more detailed and consistent error information like HAL_MMC_ERROR_DATA_CRC_FAIL, HAL_MMC_ERROR_CMD_RSP_TIMEOUT, HAL_MMC_ERROR_DMA …
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL MMC driver have been removed and replaced by _t.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Assertion implementation and usage in HAL1	The parameters and states are checked using ASSERT_DBG_STATE and ASSERT_DBG_PARAM macros.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL MMC header file remains and all macros, define statements, and functions from hal_mmc_ex.h have been moved to hal_mmc.h.
Rename LL core drivers to stm32_ppp_core.h/.c to avoid confusion with user LL drivers.	LL core driver are renamed from stm32tnxx_ll_sdmmc.h/.c to stm32tnxx_sdmmc_core.h/.c.
Add HAL PPP Services for Drivers with Handle to Retrieve Corresponding Peripheral Clock Frequency.	HAL MMC provides new API to retrieve clock frequency HAL_MMC_GetClockFreq()
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including MMC instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Optimize HAL PPP IRQ Handlers by Reordering Processes and Error Management Statements to Prioritize Critical Interrupts	The IRQ handler has been optimized by reordering processes and error management statements to prioritize critical operations.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL resources and data structures are now prefixed with HAL_MMC for improved clarity and consistency.

Other HAL MMC changes

Concept	Consideration
Increase performance and add the missing APIs for linked-list management.	New linked-list management features are added, and most linked-list operations are consolidated in a new HAL. This HAL, called HAL Q, provides advanced linked-list features and is shared between multiple HAL drivers.
Add dedicated API for retrieving the MMC Card specification version.	Introduce hal_mmc_specification_version_t HAL_MMC_GetCardSpecVersion(const hal_mmc_handle_t *hmmc).